/*
 * Copyright (c) 2024 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * @addtogroup InputMethod
 * @{
 *
 * @brief InputMethod模块提供方法来使用输入法和开发输入法。
 *
 * @since 12
 */

/**
 * @file inputmethod_text_config_capi.h
 *
 * @brief 提供输入框配置信息对象的创建、销毁与读写方法。
 *
 * @library libohinputmethod.so
 * @kit IMEKit
 * @include <inputmethod/inputmethod_text_config_capi.h>
 * @syscap SystemCapability.MiscServices.InputMethodFramework
 * @since 12
 * @version 1.0
 */
#ifndef OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H
#define OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H
#include <stdint.h>

#include "inputmethod_cursor_info_capi.h"
#include "inputmethod_text_avoid_info_capi.h"
#include "inputmethod_types_capi.h"

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
/**
 * @brief 输入框配置。
 *
 * 输入框的配置信息。
 *
 * @since 12
 */
typedef struct InputMethod_TextConfig InputMethod_TextConfig;

/**
 * @brief 创建一个新的{@link InputMethod_TextConfig}实例。
 *
 * @return 如果创建成功，返回一个指向新创建的{@link InputMethod_TextConfig}实例的指针。
 * 如果创建失败，对象返回NULL，可能的失败原因有应用地址空间满。
 * @since 12
 */
InputMethod_TextConfig *OH_TextConfig_Create(void);
/**
 * @brief 销毁一个{@link InputMethod_TextConfig}实例。
 *
 * @param config 表示指向即将被销毁的{@link InputMethod_TextConfig}实例的指针。
 * @since 12
 */
void OH_TextConfig_Destroy(InputMethod_TextConfig *config);

/**
 * @brief 设置文本配置信息中的输入框类型。
 *
 * @param config 指向即将被设置值的{@link InputMethod_TextConfig}实例的指针。
 * @param inputType 输入框的输入类型。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_SetInputType(InputMethod_TextConfig *config, InputMethod_TextInputType inputType);
/**
 * @brief 设置文本配置信息中的回车键功能类型。
 *
 * @param config 指向即将被设置值的{@link InputMethod_TextConfig}实例的指针。
 * @param enterKeyType 回车键功能类型。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_SetEnterKeyType(
        InputMethod_TextConfig *config, InputMethod_EnterKeyType enterKeyType);
/**
 * @brief 将预上屏支持情况设置到文本配置信息中。
 *
 * @param config 指向即将被设置值的{@link InputMethod_TextConfig}实例的指针。
 * @param supported 表示输入框是否支持预上屏。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_SetPreviewTextSupport(InputMethod_TextConfig *config, bool supported);
/**
 * @brief 设置文本配置信息中的选中文本范围。
 *
 * @param config 指向即将被设置值的{@link InputMethod_TextConfig}实例的指针。
 * @param start 所选文本的起始位置。
 * @param end 所选文本的结束位置。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_SetSelection(InputMethod_TextConfig *config, int32_t start, int32_t end);
/**
 * @brief 设置文本配置信息中所属窗口的窗口id。
 *
 * @param config 指向即将被设置值的{@link InputMethod_TextConfig}实例的指针。
 * @param windowId 绑定输入法的应用所属窗口的窗口id。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_SetWindowId(InputMethod_TextConfig *config, int32_t windowId);

/**
 * @brief 设置文本配置信息中的占位符文本信息。
 *
 * @param config 指向即将被设置值的{@link InputMethod_TextConfig}实例的指针。
 * @param placeholder 指向UTF-16编码的双字节指针；若传空指针，则会将占位文本信息设置为空字符串。
 * @param length placeholder指针指向内存所包含的元素个数，包含最后的字符串结尾符，计数单位为双字节。
 *                   1. 如果长度为0，占位文本信息会被设置为空字符串。
 *                   2. UTF-16编码的最大长度为255个字符（如果最后一位是字符串结尾符，不包含在计数中），超过255个字符数将会被截断。
 * @return {@link InputMethod_ErrorCode}：\n
 *     IME_ERR_OK = 0：表示成功。\n
 *     IME_ERR_NULL_POINTER = 12802000：非预期的空指针。
 * @since 20
 */
InputMethod_ErrorCode OH_TextConfig_SetPlaceholder(InputMethod_TextConfig *config, const char16_t *placeholder,
    size_t length);

/**
 * @brief 设置文本配置信息中的abilityName信息。
 *
 * @param config 指向即将被设置值的{@link InputMethod_TextConfig}实例的指针。
 * @param abilityName 指向UTF-16编码的双字节指针；若传空指针，则会将abilityName设置为空字符串。
 * @param length abilityName指针指向内存所包含的元素个数，包含最后的字符串结尾符，计数单位为双字节。
 *                   1. 如果长度为0，abilityName会被设置为空字符串。
 *                   2. UTF-16编码的最大长度为127个字符（如果最后一位是字符串结尾符，不包含在计数中），超过127个字符数将会被截断。
 * @return {@link InputMethod_ErrorCode}：\n
 *     IME_ERR_OK = 0：表示成功。\n
 *     IME_ERR_NULL_POINTER = 12802000：非预期的空指针。
 * @since 20
 */
InputMethod_ErrorCode OH_TextConfig_SetAbilityName(InputMethod_TextConfig *config, const char16_t *abilityName,
    size_t length);

/**
 * @brief 获取文本配置信息中的输入框类型。
 *
 * @param config 指向即将被获取值的{@link InputMethod_TextConfig}实例的指针。
 * @param inputType 表示指向{@link InputMethod_TextInputType}实例的指针。
 输入框的输入类型。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_GetInputType(InputMethod_TextConfig *config, InputMethod_TextInputType *inputType);
/**
 * @brief 获取文本配置信息中的回车键功能类型。
 *
 * @param config 指向即将被获取值的{@link InputMethod_TextConfig}实例的指针。
 * @param enterKeyType 表示指向｛@link InputMethod_EnterKeyType｝实例的指针。
 输入框的回车键功能类型。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_GetEnterKeyType(
    InputMethod_TextConfig *config, InputMethod_EnterKeyType *enterKeyType);
/**
 * @brief 获取文本配置中是否支持预上屏。
 *
 * @param config 指向即将被获取值的{@link InputMethod_TextConfig}实例的指针。
 * @param supported 表示输入框是否支持预上屏。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_IsPreviewTextSupported(InputMethod_TextConfig *config, bool *supported);
/**
 * @brief 获取文本配置信息中的光标信息。
 *
 * @param config 指向即将被获取值的{@link InputMethod_TextConfig}实例的指针。
 * @param cursorInfo 光标信息。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_GetCursorInfo(InputMethod_TextConfig *config, InputMethod_CursorInfo **cursorInfo);

/**
 * @brief 获取文本配置信息中的避让信息。
 *
 * @param config 表示文本配置信息。
 * @param avoidInfo 输入框避让信息。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 *@since 12
 */
InputMethod_ErrorCode OH_TextConfig_GetTextAvoidInfo(
    InputMethod_TextConfig *config, InputMethod_TextAvoidInfo **avoidInfo);

/**
 * @brief 获取文本配置信息中的选区范围信息。
 *
 * @param config 指向即将被获取值的{@link InputMethod_TextConfig}实例的指针。
 * @param start 所选文本的起始位置。
 * @param end 所选文本的结束位置。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */
InputMethod_ErrorCode OH_TextConfig_GetSelection(InputMethod_TextConfig *config, int32_t *start, int32_t *end);
/**
 * @brief 获取文本配置信息中所属窗口的窗口id。
 *
 * @param config 指向即将被获取值的{@link InputMethod_TextConfig}实例的指针。
 * @param windowId 绑定输入法的应用所属窗口的窗口id。
 * @return 返回一个特定的错误码。
 *     {@link IME_ERR_OK} - 表示成功。
 *     {@link IME_ERR_NULL_POINTER} - 非预期的空指针。
 * 具体错误码可以参考{@link InputMethod_ErrorCode}。
 * @since 12
 */

InputMethod_ErrorCode OH_TextConfig_GetWindowId(InputMethod_TextConfig *config, int32_t *windowId);
/**
 * @brief 获取文本配置信息中的占位符文本信息。
 *
 * @param config 指向即将被获取值的{@link InputMethod_TextConfig}实例的指针。
 * @param placeholder 用于存放占位文本信息，该指针内存由调用者维护。
 * @param length 占位文本信息长度，计数单位为双字节，长度包含字符串结尾符。
 *                  1. 作为入参，代表placeholder指向的内存可用长度。作为出参，代表实际的占位文本长度。
 *                  2. 如果placeholder为空指针，且length指向有效内存，则length会被填充实际的占位文本长度。接口会返错。
 *                  3. 如果placeholder和length都指向有效内存，但length传入的长度小于实际的占位文本长度，则length会被填充实际的占位文本长度。接口会返错。
 * @return {@link InputMethod_ErrorCode}：\n
 *     IME_ERR_OK = 0：表示成功。\n
 *     IME_ERR_PARAMCHECK = 401：参数检查失败。\n
 *     IME_ERR_NULL_POINTER = 12802000：非预期的空指针。
 * @since 20
 */
InputMethod_ErrorCode OH_TextConfig_GetPlaceholder(InputMethod_TextConfig *config, char16_t *placeholder,
    size_t *length);

/**
 * @brief 获取文本配置信息中的abilityName信息。
 *
 * @param config 指向即将被获取值的{@link InputMethod_TextConfig}实例的指针。
 * @param abilityName 用于存放abilityName，该指针内存由调用者维护。
 * @param length abilityName长度，计数单位为双字节，长度包含字符串结尾符。
 *                  1. 作为入参，代表abilityName指向的内存可用长度。作为出参，代表实际的abilityName长度。
 *                  2. 如果abilityName为空指针，且length指向有效内存，则length会被填充实际的abilityName长度。接口会返错。
 *                  3. 如果abilityName和length都指向有效内存，但length传入的长度小于实际的abilityName长度，则length会被填充实际的占位文本长度。接口会返错。
 * @return {@link InputMethod_ErrorCode}：\n
 *     IME_ERR_OK = 0：表示成功。\n
 *     IME_ERR_PARAMCHECK = 401：参数检查失败。\n
 *     IME_ERR_NULL_POINTER = 12802000：非预期的空指针。
 * @since 20
 */
InputMethod_ErrorCode OH_TextConfig_GetAbilityName(InputMethod_TextConfig *config, char16_t *abilityName,
    size_t *length);
#ifdef __cplusplus
}
#endif /* __cplusplus */
/** @} */
#endif // OHOS_INPUTMETHOD_TEXT_CONFIG_CAPI_H